Itential Docs & Guides | Drive Automation for Modern Networks

Integration Models UI

The main user interfaces (UI) for Admin Essentials | Integration Models are described below. Please note that available views, features, and interactions in the UI can be limited based on user permissions.

Create Integration Model

To create (import) an Integration Model:

Access IAP and navigate to Admin Essentials.
Click the Import icon in the top toolbar to display the Import dialog.
Select Integration Model from the dropdown. The Import File modal will display.
You can upload your Integration Model File by drag-and-drop, or click Browse Files to find and select the file you want to upload.
Once the file is uploaded, the Name of the Integration Model will pre-populate from the specification file, along with a description. You can change the description, as needed, to provide specific information for your import and to better communicate what this integration is used for within your platform.
When you upload a Swagger 2.0 or OpenAPI 3.0 specification file, you can run validation on it using the Validate (✓) button. The OpenAPI specification file must be obtained from the targeted integration. For example, gitlab, amazon, and jenkins provide OpenAPI specifications that properly describe their APIs. Admin Essentials can ingest these files and enable integration with these technologies within IAP.
Once you click the Import button, and upon successful import, the Integration Model will be added to the collection list in the left sidebar.
When you select the Integration Model from the collection list you will be redirected to the Integration Model Details page.

Current OpenAPI Support

Swagger 2.0 and OpenAPI 3.0 are currently supported for creating an Integration Model. A Swagger 2.0 document is converted to an OpenAPI 3 document on import. All OpenAPI 3.0 documents must conform to the OpenAPI v3.0 Specification.

Current Limitations

Described below are known limitations with regard to creating an Integration Model.

Servers

Currently a single server endpoint is supported for Integrations. If the OpenAPI document has more than one server listed in its servers object, the first server will be selected for use. This endpoint can be updated in the service configuration after the Integration is created.

Example Template for Single Server Endpoint

Any server URL using the OpenAPI path template expressions will have the default value for variables applied. Below is an example of a configuration using multiple servers and URLs using path template expressions.

"servers": [
    {
      "description": "The s3 multi-region endpoint",
      "url": "https://s3.{region}.amazonaws.com",
      "variables": {
        "region": {
          "default": "us-east-2",
          "description": "The AWS region",
          "enum": [
            "us-east-1",
            "us-east-2",
            "us-west-1",
            "us-west-2"
          ]
        }
      }
    },
    {
      "description": "The s3 multi-region endpoint",
      "url": "https://s3.{region}.amazonaws.com",
      "variables": {
        "region": {
          "default": "us-east-1",
          "description": "The AWS region",
          "enum": [
            "us-east-1",
            "us-east-2",
            "us-west-1",
            "us-west-2"
          ]
        }
      }
    }
]

The resulting URL used in the service configuration will be the following:

https://s3.us-east-2.amazonaws.com/

This URL result was determined by taking the first server listed in the array and applying the default variable values to the template URL. Again, this URL can be edited in the service configuration after the Integration is created.

Security Schemes and Token Management

By default and upon import of an Integration Model, only a single security scheme is supported. Furthermore, the first scheme in the securityScheme map will be selected automatically.

Supported Security Schemes

The following security schemes are supported:

apiKey (including AWS)
http
oauth2

The openIdConnect scheme is NOT currently supported.

Once the Integration is created, an authentication object is added to the properties of the service configuration. This configuration corresponds to the security scheme type. Below is an example of the authentication format.

Important Notes:

Currently IAP does NOT support any token management. You will need to manage the tokens for the security schemes.
For Amazon Web Services (AWS), please ensure the securityScheme entry is an apiKey and has the following extension: "x-amazon-apigateway-authtype": "awsSigv4".

"securitySchemes": {
        "Authorization": {
            "type": "apiKey",
            "description": "Amazon S3 signature",
            "name": "Authorization",
            "in": "header",
            "x-amazon-apigateway-authtype": "awsSigv4"
        }
    }

Listed below are examples of each of the different security schemes that can be used with Integration Models. The property names API-Token and Authorization in the API Key and AWS examples come from the name of the securityScheme property in the OpenAPI document.

API Key

"authentication": {
  "API-Token": {
    "value": ""
  }
},

AWS

"authentication": {
  "Authorization": {
    "accessKeyId": "",
    "secretAccessKey": ""
  }
},

HTTP (Basic & Bearer)

Basic

"authentication": {
          "httpBasic": {
            "username": "",
            "password": ""
          }
      },

Bearer

"authentication": {
          "bearerAuth": ""
      },

Oauth2

"authentication": {
  "oauth2": {
    "token": {
      "access_token": "",
      "token_type": "Bearer"
    }
  }
},

Admin Essentials

Help us improve by sending feedback...

On this page:

Integration Models